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1 . Scope 

Wireless Application Protocol (WAP) is a result of continuous work to define an industry-wide specification for 
developing applications that operate over wireless communication networks. The scope for the WAP Forum is to define a 
set of standards to be used by service applications. The wireless market is growing very quickly and reaching new 
customers and services. To enable operators and manufacturers to meet the challenges in advanced services, differentiation 
and fast/flexible service creation, WAP defines a set of protocols in transport, session and application layers. For 
additional information on the WAP architecture, refer to Wireless Application Protocol Architecture Specification 
[WAP ARCH]. 

This document specifies the library interface for WMLScript [WMLScript] to provide cryptographic functionality of a 
WAP client. In addition this document specifies a signed content format to be used to convey signed data to/from WAP 
devices. This functionality complements transport layer security provided by [WAPWTLS]. 

The notation and other conventions related to describing a WMLScript library are according to [WMLScript] and 
[WMLSSL]. 
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2. Document Status 

This document is available online in the following formats: 
• PDF format at http://www.wapforum.org/. 

2.1 Copyright Notice 

© Copyright Wireless Application Forum Ltd, 1999 all rights reserved. 

2.2 Errata 

Known problems associated with this document are published at http://www.wapforum.org/. 



2.3 Comments 

Comments regarding this document can be submitted to the WAP Forum in the manner published at 
http://www.wapforum.org/. 
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4. Definitions and Abbreviations 
4.1 Definitions 

The following are terms and conventions used throughout this specification. 

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", 
"RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in [RFC21 19]. 

Please refer to [WMLScript] and [WMLSS] for WMLScript related terminology. 



4.2 Abbreviations 

For the purposes of this specification, the following abbreviations apply: 



API 


Application Programming Interface 


CA 


Certification Authority 


ECMA 


European Computer Manufacturer Association 


HTTP 


HyperText Transfer Protocol [RFC2068] 


LSB 


Least Significant Bits 


MSB 


Most Significant Bits 


PKCS 


Public-Key Cryptography Standards 


RFC 


Request For Comments 


RSA 


Rivest Shamir Adleman public key algorithm 


SHA 


Secure Hash Algorithm 


UI 


User Interface 


URL 


Uniform Resource Locator 


W3C 


World Wide Web Consortium 


WWW 


World Wide Web 


WSP 


Wireless Session Protocol 


WTLS 


Wireless Transport Layer Security 


WTP 


Wireless Transport Protocol 


WAP 


Wireless Application Protocol 


WAE 


Wireless Application Environment 


WTA 


Wireless Telephony Applications 


WTAI 


Wireless Telephony Applications Interface 


WBMP 


Wireless BitMaP 


WIM 


WAP Identity Module 
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5. 



Cryptographic Library Description 



Description: 



Name: 



Library ID: 



Crypto 

To be assigned. 

This library contains cryptographic functions. 



The current library specification supports digital signature functionality . Other functionality (like encryption/decryption or 
symmetric key based MAC) may be added in future versions. 



Many kinds of applications, e.g., electronic commerce, require the ability to provide persistent proof that someone has 
authorised a transaction. Although WTLS [W APWTLS] provides transient client authentication for the duration of a 
WTLS connection, it does not provide persistent authentication for transactions that may occur during that connection. 
One way to provide such authentication is to associate a digital signature with data generated as the result of a transaction, 
such as a purchase order or other financial document. 

To support this requirement, the browser provides a WMLScript function, Crypto. signText, that asks the user to sign a 
string of text. A call to the signText method displays the exact text to be signed and asks the user to confirm that. After the 
data has been signed and both the signature and the data have been sent across the network, the server can extract the 
digital signature and validate it, and possibly store it for accountability purposes. 

The browser SHOULD use special signature keys that are distinct from authentication keys used for WTLS. A WIM 
[WAPWIM] may be used for private key storage and signature computation. 



5.1 



signText 



5.1.1 



Introduction 
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5.1 .2 signText function definition 



Function: signedString = Crypto.signTeKt(stringToSign, options, keyldType, keyld) 

Function ID: 16 

Description: The function requests that a user digitally signs a text string. The calling script provides the 

text to sign (stringToSign) which MUST be displayed to the user. The user may choose 
either to cancel or approve the signing operation. If several certificates are available that 
match the criteria indicated in parameters, the choices should be indicated to the user, using 
e g labels of the certificates. If the user approves the operation, the browser MUST ask for 
user verification information for the private key (e.g., the WIM PIN for a non-repudiation 
key). If the user enters the correct information, signText signs the specified string and returns 
signedString to the script as String, formatted as base-64 [RFC1521] encoding of 
SignedContent. 

Parameters: stringToSign = String 

A string which MUST be displayed to the user. Note that the character set of this string is 
indicated in the context where the script is contained. 

options = Integer 
Contains several option values, ORed together: 

0x0001 - INCLUDE_CONTENT . If this option is set, the browser MUST include the 
stringToSign in the result. 

0x0002 - INCLUDE_KEY_HASH. If this option is set, the browser MUST include the 
hash of the public key corresponding to the signature key in the result. 
0x0004 - INCLUDE.CERTIFICATE. If this option is set, the browser MUST include the 
certificate or a URL of the certificate in the result (whether the browser includes the 
certificate content or a URL depends on which one is available). If the browser does not 
have access to a certificate, it MUST return "erronnoCert". 

keyldType = Integer 

Indicates the type of a key identifier: 

0 - NONE. No key identifier is supplied. The browser may use any key and certificate 
available. 

1 - USER_KEY_HASH. A SHA- 1 hash of the user public key is supplied in the next 
parameter. The browser MUST use the signature key that corresponds to the given public 
key hash or, if this key is not available, return "error :noCert" . 

2 - TRUSTED_KEY_HASH. A SHA-1 hash of a trusted CA public key (or multiple of 
them) is supplied in the next parameter. The browser MUST use a signature key that is 
certified by the indicated CA (or some of them). If no such key is available, the browser 
MUST return "error :noCert'\ 

keyld - String 

Identifies the key in a way based on the previous parameter. 

For a SHA-1 public key hash, contains the 20-byte hash. Multiple values may be 
concatenated. Number of elements in the list is implied by the length of the parameter. 
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Return value: 



Exceptions: 
Example: 



String or Invalid. 

The content of the return string is the following 

• in case of a succesful operation, the base-64 [RFC1521] encoding of SignedContent 

• if there is no proper certificate or signature key available, the string "error:noCerf 

• if the user cancelled the operation, the string "error: userCancel" 

Errors in parameters, encoding or internal errors result in an invalid return value. 

var foo = Crypto. signText ( "Bill of Sale\n \n3 

Bolognese $18.00\nl Pepperoni $7.00\n4 Lemonade $6.00\n 

\nTotal Price $31.00", 

0,1, 

" \x3 7\xQ0\xB6\x96\x37\x7 5\xE3\x93\x48\x74\xD3\x98\x47\x53\x94\ 
x34\x5 8\x97\xB5\xD6" ) ; 

// The application indicates the signature key 



5.1 .3 Handling of Certificates 

For verification of the digital signature, the server must have access to a user's certificate that is signed by a Certification 
Authority (CA) recognised by the server. There are several possibilities for how the server can get access to the user's 
certificate: 

1. The certificate is appended to the signature. 

2. The public key hash is appended to the signature. The server is able to fetch the corresponding certificate from a 
certificate service. 

3. A URL of the certificate is appended to the signature. The server is able to fetch the certificate using internet methods. 

4. The server knows the user certificate based on a previous data exchange with the user, e.g., a previous digital 
signature. 

5.1 .4 Implementation using the WIM 

This chapter describes how to implement the signText function using the WIM [WAPWIM]. 

A non-repudiation key is used for signing. This implies usage of a an authentication object used for this key only, and that 
the verification requirement cannot be disabled. E.g., in case of a PIN, the PIN MUST be entered separately for each 
signature operation. 

The PKCS#15 key ID (commonObject Attributes. id) has the value of the public key hash. So, it can be used to find the 
proper key or certificate, if the key is identified by USER_KEY_HASH. The certificate issuer public key hash 
(PKCSI5CommonCertificateAttributes.requestId) can be used to find a proper certificate, if it is identified by 
TRUSTED_KEY_HASH. 

Labels, contained in entries that describe private keys and certificates (commonObjectAttributes.label) SHOULD be used 
to display options to use for signing. 

For a smart card implementation, the procedure is described in [WAPWIM], chapter 1 1.4.6. 
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6. Format of SignedContent 

This section defines a format for transmission of signed content to/from WAP devices. It is described below using WTLS 
presentation [WAPWTLS]. Hash values of authenticated attributes are computed using a PKCS#7 template to provide 
end-to-end authentication between WAP clients and devices supporting the PKCS#7 standard for signed data 
representation. 



enum {null ( 0 ) , rsa_sha_pkcsl ( 1 ) , ecdsa_sha_pl3 63 ( 2 ) , (255)} 
DataSignatureAlgorithm; 



Item 


Description 


null 

rsa_sha_pkcs 1 
ecdsa_sha 


No signature present. 

The signature is calculated according to [PKCS1] (see Appendix B), using octet string output. 
The signature is calculated according to [X9.62], using octet string output. 



struct { 

DataSignatureAlgorithm algorithm; 
switch (algorithm) { 
case null: struct {}; 

default: opaque signature<0 . . 2 "16-1> ; 

}; 

} Signature ; 



enum { implicit(O), sha_key_hash < 1 ) , wtls_certif icate ( 2 ) , x509_certif icate ( 3 ) , 
x968_certif icate (4) , cert if icate_url ( 5 ) , (255)} Signerlnf oType ; 



Item 


Description 


implicit 


The signer is implied by the content. 


sha_key_hash 


The SHA-1 hash of the public key, encoded as specified in [WAPWTLS]. 


wtls_certificate 


A WTLS certificate. 


x509_certificate 


AnX.509v3 certificate. 


x968__certificate 


An X9.68 certificate. 


certificate_url 


A URL where the certificate is located. 



struct { 

Signerlnf oType signer_inf o_type ; 
switch (signer_inf o_type) { 
case implicit: struct {}; 
case s ha_key_ha s h : 
opaque hash [20] ; 
case wtls_certif icate : 

WTLSCertif icate; 
case x509_certif icate : 

opaque x509_certif icate<0 . . 2 A 16-1>; 
case x968_certif icate : 

opaque x9 68_certif icate<0 . . 2 A 16-1 ; 
case certif icate_url : 
opaque url<0..2 55>; 
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}; 

} Signerlnfo; 



enum (text(l), data (2), (255)} ContentType; 



Item 


Description 


text 
data 


Encoded text (according to character set). 

Encoded data (encoding indicated by content_encoding parameter, see below). 



enum ( false (0), true(l)} Boolean; 

struct { 

ContentType content_type ; 
uintl6 content_encoding; 
Boolean content present ; 
switch (content ^present) { 
case false: struct{); 

case true: opaque content<0 . . 2 A 16-l> ; 

}; 

} Contentlnfo; 



Item 



Description 



content_type 
content_encodi ng 



content_present 
content 



The type of the content that was signed. 

For text type of content, indicates the character set used to encode the text before signing (I AN A 
assigned character set number, see [WAPWSP]). The recommended character set is UTF-8 
[UTF8]. Note that the hash is calculated over the encoded text (no length indication, terminating 
character or character set indicator is included). 

For data type of content, indicates a specific content type (assigned values are not defined yet). 

Indicates if the content is present in the structure. 

Content. 



enum { gmt__utc_time ( 1 ) , signer.nonce (2 ) , (255) } AttributeType ; 



Item 



Description 



gmt_utc_time 
signer_nonce 



The current time and date in UTC format (see Appendix C). Only the 12 actual date/time octet 
values are included; the trailing 4 Z\ indicating GMT or Zulu, is omitted since it is implicit. 

A nonce generated by the signer. This attribute MAY be used by devices that do not have an 
internal clock. 



struct { 

AttributeType at tribute_type ; 
switch (attribute_type) { 

case gmt_utc_time: uint8[12]; 

case signer_nonce: opaque signer_nonce [ 8 ] ; 

} 

} AuthenticatedAttribute ; 



struct { 



(c) copyright Wireless Application Forum, Ltd, 1999 

All rights reserved. 



I Version 05-Nov-1999 Vor c ion 05 - Nov - 1999 Propo c od Vor oi on 05 - Nov26 - Aug - 1999 



Page 
14(184) 



uint8 version ; 
Signature signature; 

Signerlnfo signer_inf os<0 . ,2 ys 16-l>; 
Content Info content_inf o; 

AuthenticatedAttribute authenticated_attributes<0 . . 255>; 
} SignedContent ; 



Item 


Description 


version 


Version of the SignedContent structure. For this specification the version is 1. 


signature 


Signature 


signer_infos 


Information on the signer. This may contain zero items (in case the signer is implicit). Also, 
there may be multiple items of Signerlnfo present (public key hash and a certificate). 


content_info 


Content that was signed. The actual content is optionally included in the structure. 


authenticated_ 


Attributes that are included in the signature. 


attributes 





6.1 . Usage with signText 

The result returned by signText is formatted as SignedContent. The original stringToSign is optionally included in the 
structure. It is the responsibility of the application that the verifying party (server) will have access both to the original text 
and the signature. The text may be generated in the server and cached there. Or, if the text is generated in the client (e.g., 
based on user input), it should be included in the structure. 

The verification service must take the character set into account. If the original service generated the stringToSign, it is 
necessary to convert that to a proper character set encoding. 

6.2. Hash Calculation and Relationship to PKCS#7 SignedData 

The signed content type is defined so as to allow end-to-end authentication of signed content based on PKCS#7 [PKCS7] 
signed data structures. A proxy server or gateway may accept a PKCS#7 signed data object and convert to the WAP signed 
content type without violating the end-to-end integrity of the signature. This is done by compressing the PKCS#7 header 
(by representing it in WTLS encoding format) without information loss. Since the mobile device can reconstruct the 
original header with any authenticated attributes it can verify the original signature. 

When a mobile device is sending signed content it constructs the PKCS#7 header using a static template and filing in the 
relevant attribute values. The hash is computed as specified in [PKCS7]. The mobile device then formats and sends the 
SignedContent type. This allows a proxy or gateway to convert this back to PKCS#7 format for transmission to a server. In 
this way we achieve both bandwidth efficiency and limited parsing requirements on the mobile device while enabling end- 
to-end signed content verification with servers not supporting the WAP signed content type. 

The hash calculation on the mobile device is performed as defined in [PKCS7], using the signer's authenticated attributes. 
This requires that the input for the hash calculation is represented in ASN.l DER encoding. As shown below, complex 
DER encoding is not required, since the length of the values are known beforehand. An implementation needs only the 
(static) PKCS#7 DER structure, filing in the variable fields. It need not understand the specifics of the ASN.l encoding. 

According to [PKCS7], the mandatory authenticated attributes are the contentType and messageDigest attributes (hash of 
the original data). Additionally, either signing time or a random nonce MUST be used as an authenticated attribute. 
Signing time is recommended. A random number MAY be used by implementations that do not support real time clock. 

The message-digesting process computes a message digest on the content together with the signer's authenticated 
attributes. The initial input to the message-digesting process is the value of the content being signed. 
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The authenticated attributes are the following [PKCS9]. 



Attribute 



OID 



OID in Binary 



contentType 
messageDigest 



pkcs9-3 
pkcs9-4 
pkcs9-5 



2a 86 48 86 f7 OdOl 09 03 



2a 86 48 86 f7 OdOl 09 04 



signingTime 
signerNonce 



2a 86 48 86f7X)d01 09 05 



pkcs9-25-3 



2a 86 48 86 f7 Od 01 09 19 03 (tentative, to be confirmed) 



To calculate the 



hash, the signer uses the following buffer as a template: 



31 57 



30 16 

06 09 2a 86 48 86 f7 Od 01 09 03 -- contentType 

06 09 2a 86 48 86 f7 Od 01 07 01 — data 
30 la 

06 09 2a 86 48 86 f7 Od 01 09 05 — signingTime 

17 Od xx xx xx xx xx xx xx xx xx xx xx xx xx UTCTime 
30 21 

06 09 2a 86 48 86 f7 Od 01 09 04 -- messageDigest 

04 14 XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX 



In order to construct the input for hash calculation, the following steps are performed 

• use initially a 89-byte buffer as above (bytes 1 ...89) 

• replace bytes 42...S4 with the value of UTC time expressed as YYMMDDHHMMSSZ (ASCII-encoded) 

• replace bytes 70...89 with the 20-byte value of the SHA-1 hash 

The next step is to calculate the hash from the above 89-byte buffer. Finally, the signature is calculated. 

Note that the PKCS#7 contentType "data" is used for both text and data content types specified in the beginning of this 
chapter. 

For verification, the above structure needs to be constructed based on values transmitted in SignedContent: content_type, 
gmt_utc_time. 

Note that the authenticated attributes are included in the in ascending order compared as octet strings. 

A proxy server MAY construct a PKCS#7 [PKCS7] SignedData object based on a received SignedContent object. The 
motivation of doing this would be that some internet or other service applications may require a PKCS#7 formatted object 
to verify the signature. The conversion to PKCS#7 is based on the original text, the signature and a certificate. 

A proxy server MAY also convert a PKCS#7 SignedData object to a SignedContent object for transmission to a mobile 
device. 

When the mobile device receives (e.g. over WSP) a SignedContent object (containing text or any type of data), it should 
verify the signature and be able to present information on the signer and the result of verification: if it was succesful, or if it 
failed with different reasons, like invalid signature or inability to verify the signer's certificate. When the SignedContent 
object contains signed text, the original text and result of verification must be presented in a manner which is distinctive 
from texts generated by applications using e.g. WML or WMLScript. 



SHA-1 



digest 
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Appendix A. Library Summary 

The libraries and their library identifiers: 



Library name 


Library ID 


Page 


Crypto 


to be assigned 





The libraries and their functions: 



Crypto library 


Function ID 


signText 


16 
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Appendix B. RSA PKCS#1 Signature Calculation 

The calculation is based on [PKCS1], chapter 10.1. It consists of three steps: message digesting (hashing), data encoding 
and RSA encryption. (The fourth step, octet-string-to-bit-string conversion is not necessary here.) 

The message (the text being signed) is digested using SHA-1 [SHAi]. The 20-byte output and a SHA-1 algorithm 
identifier shall be combined into an ASN.l [ASN1] value of type Digestlnfo, described below, which shall be DER- 
encoded [DER] to give an octet string, the data. 

Digestlnfo SEQUENCE { 

digestAlgorithm DigestAlgorithmldent if ier , 
digest Digest } 

DigestAlgorithmldentif ier ::= Algorithmldentif ier 

Digest ::= OCTET STRING 

digestAlgorithm identifies the message-digest algorithm. For this application, it should associate the SHA-I 
algorithm. The object identifier is the following 

sha-1 OBJECT IDENTIFIER 

{ iso(l) identif ied-organization ( 3 ) oiw(14) secsig(3) 2 26 } 

The BER encoding of the above is: 2b Oe 03 02 la 

digest is the result of the message digesting process, ie, the message digest. 

The BER encoding of Digestlnfo is 

30 21 
30 09 

06 05 2b Oe 03 02 la 
05 00 
04 14 

XX XX XX XX 
XX XX XX XX 
XX XX XX XX 
XX XX XX XX 
XX XX XX XX 

where the last 20 bytes is the message digest- So, in order to implement the BER-encoded Digestlnfo, it is sufficient to 
concatenate the constant 15 bytes and the 20 bytes of the hash. 

The resulting data (BER-encoded Digestlnfo), is encrypted with the signer's private key as described in [PKCS1] 
section 7, using the block type i. The resulting octet string, is the signature. 



— SEQUENCE (Digestlnfo) 

— SEQUENCE (Algorithmldentif ier) 
-- digestAlgorithm = sha-1 

-- parameters = NULL 

— OCTET STRING (digest) 
digest value 



(c) copyright Wireless Application Forum, Ltd, 1999 

All rights reserved. 



i 



Version 05-Nov-1999 V o r s ion 05 - Nov -1 99 9 Propoood Ver s ion 05 - Nov26 - Aug - 1999 Page 
' 18(184) 



Appendix C. UTC Time 

The universal time type, UTCTime, is a standard ASN.l type intended for international applications where local time 
alone is not adequate. UTCTime specifies the year through the two low order digits and time is specified to the precision 
of one minute or one second. UTCTime includes either Z (for Zulu, or Greenwich Mean Time) or a time differential. 

For the purposes of this profile, UTCTime values MUST be expressed Greenwich Mean Time (Zulu) and MUST include 
seconds (i.e., times are YYMMDDHHMMSSZ), even where the number of seconds is zero. Conforming systems MUST 
interpret the year field (YY) as follows: 

Where YY is greater than or equal to 50, the year shall be interpreted as 19YY; and where YY is less than 50, the year 
shall be interpreted as 20YY. 

The above usage is as is specified in [RFC2459]. 

For transmission in the signed content AuthenticatedAt tribute type (gmt_utc_time) the trailing Z' is 
omitted as it is implicit. 
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